Mac Magazin/MacEasy 19/Mac Magazin and MacEasy Magazine CD - Issue 19.iso/Utilities/uae-0.4/README

Text File | 1996-02-13 | 21KB | 445 lines

This is version 0.3 of UAE, the Un*x Amiga Emulator.

1. <drivel.h>

Copyright 1995, 1996 Bernd Schmidt & contributors (see below). This program is
freeware.  You may do whatever you want with it for personal use. Permission
is granted to redistribute this program free of charge, provided it is
distributed in the full archive with unmodified contents and no profit beyond
the price of the media on which it is distributed is made. Exception: It may
be included on freeware/shareware collections on CD-ROM.
There are no warranties of any kind for this program. If you use this program,
you do so at your own risk. The authors are not responsible for any damages
that might result from using this program.
This program is still in an early development stage. It contains bugs and is
not user-friendly.

2. What you need to get it to work

  - a Un*x system with the X Window System, or, if you use Linux, SVGAlib.
    X is much more stable and not that much slower, so use X if possible.
    SVGAlib can get your system into an unusable state if it crashes. You
    have been warned.
  - A graphics card that lets you use a resolution of at least 800x600 in
    65536 colors. You can compile UAE for 256 color screens, but the colors
    will not be quite as good.
  - a C compiler. An _ANSI_ C compiler. What most workstation vendors ship
    is not a compiler, but a nightmare. Use GCC if it is available.
  - A Kickstart ROM file. I've heard success reports with Kickstart 1.3, 2.0,
    3.0 and 3.1 from various people.
    There seem to exist special 68020+ versions of newer Kickstarts. These
    will not work, neither will EPROM versions, and neither will ZKick files.
    Please don't ask me to send you one, I have not asked Commodore/Escom for
    permission yet, and until I do, I won't give any away.
    This version of the emulator can also boot some programs without a
    Kickstart. See below for more information.

I've successfully tested UAE on the following systems:
  - Pentium-90, Linux 1.3.45; X11R6 (XFree86 3.1.1) / SVGAlib 1.2.9, GCC 2.7.2
  - HP Apollo, HP-UX, X11R5, GCC 2.6.0
  - Sun Sparcstation, Solaris, OpenWindows, GCC 2.6.1

Several people have successfully run previous versions on a variety of
systems, including a SGI Indy, Suns, a DEC Alpha and a m88k based Unix box.

3. Installation

Please note: I know that the installation procedure could be improved. I
always hate it if I have to change the Makefile or header files to install a
program. But this is the best I could come up with so far.

To build UAE, first unpack it to an appropriate directory (e.g. /usr/src/uae
on a Linux system). After that, you will have to edit the file config.h. There
are many configuration options, each with a comment describing the purpose.
Please read everything carefully.
Unlike in previous versions, you should not need to edit the Makefile.
However, if X11 is installed in a different place on your system, you might
need to change the "/usr/X11R6/" bits to "/usr/X11R5" or whatever is
appropriate.
The Makefile knows about a variety of systems. Do "make linux" to compile for
the X Window System under Linux. Do "make svga" to use SVGAlib. There are
several other systems: Do just "make" to get a list. If nothing else works,
try "make withgcc", and if that does not work because GCC is not installed,
"make generic". When that fails, send me an email.
If you use SVGAlib, be warned that SVGAlib is not too stable and using it is
inherently a little dangerous, you might want to have a way to log in from a
remote terminal if things go horribly wrong. If you are very unfortunate, you
might lock up your machine otherwise (I strongly recommend using X - it is
no longer much slower).

The compilation may take a while, especially for the cpu*.c files. There might
be some warnings, ignore these. It may also take a lot of memory. You should
have at least 8MB physical RAM to compile this, plus maybe 20MB swap and 9MB
filesystem space.

After compilation, you'll need to install the ROM image. This must have a size
of exactly 512K and should be an image of the addresses 0xF80000-0xFFFFFF on
your Amiga system. The file must be called kick.rom to be recognized. Please
read the next section on how to transfer files from your Amiga to your PC.

You can also install a disk image file. This must be called df0.adf (adf =
Amiga Disk File), and should be a raw image of the data on the floppy disk:
11x2x80 sectors == 901120 bytes.
Please try running UAE without a diskfile first. If everything went O.K., the
emulator should show the Kickstart logo (don't be too impatient, this will
take a while on slow machines).

If you don't have a Kickstart file, you may still be able to boot some games
and demos. The emulator includes code that will try to read and execute the
bootblock of the diskfile you are using, and if that bootblock only uses the
one or two Kickstart functions that are supported by the "replacement
Kickstart", your program will boot. Don't expect too much, though.

4. Invoking UAE

After building the program, you should have an executable called "uae". You
can simply execute it, but you can also optionally give it one of the following
parameters:

 -d      : If UAE is not configured to use correct-aspect display by default,
           this option will enable it.
 -f rate : Sets the frame rate
 -D      : Don't start the emulator at once, use the built-in debugger.
 -x      : (X Windows only) Enable a slower, but more portable version of the
           drawing routines. If you need this switch, I'd like to hear about
       it (it seems unlikely).
 -l lang : Set the keyboard language at run-time. Currently, only two values
           can be used for lang: "us" for U.S. keyboard (default), or "de" for
       german keyboard.
 -s      : Emulate slow memory at 0xC00000. This is known to cause problems,
           there's a bug somewhere. But some demos expect to find this type
       of memory, and they can occasionally be made to work with this
       switch.
 -S      : If you set the LINUX_SOUND option in config.h, you can turn off
           sound output with this switch.
 -M VOLUME:path
 -m VOLUME:path
           mount the unix file system at path as an Amiga filesystem with
       volume name "VOLUME:". For example, "-M sound:/usr/amiga/modules"
       If you use -M instead of -m, the volume will be read only.
       See below.

If you use SVGAlib, the only way to leave the program is pressing F12.

5. Harddisk emulation

Using diskfiles is awkward. There are two ways how you can use larger amounts
of data with UAE.

a) Harddisk files.
You can create a harddisk file with

  dd if=/dev/zero of=hardfile bs=512 count=16384

Currently, the size is fixed (8MB). This might be configurable in future
versions.
The harddisk file is accessed by a resident ROM module that is built into the
emulator. It's called "uae.device", the DOS name for the harddisk is "uae0:".
You have to format it before use (from AmigaDOS).

b) Access unix filesystems from the emulator.

This has some major advantages:
 - It doesn't crash the emulator if you are using Kickstart 1.3
 - It is more convenient.
 - It is much faster. In fact, it can be dramatically faster even than a real
   Amiga when reading directories.

If you specify the -M or -m command line arguments, you can use files on your
Unix filesystem from the emulator. If you start UAE with

  uae -m sound:/usr/amiga/modules

you can access all the files in /usr/amiga/modules by reading from the
AmigaDOS volume "SOUND:".
If you want to execute files, they need to have the x permission bit set.

In theory, you can specify this option multiple times. In practice, this
doesn't work with Kickstart 1.3 and was therefore turned off. This will get
fixed.

6. Tools

In the "amiga" subdirectory you'll find two small tools that you can use to
transfer software from the Amiga to the PC. These are called transrom and
transdisk. transrom will dump the contents of your Kickstart ROM, and
transdisk will dump an image of the floppy in drive DF0:. Both programs write
to the standard output, so you want to redirect that. Do

   transrom >ram:kick.rom

to create a file called "kick.rom" in the RAM disk, and

   transdisk >ram:df0.adf

to create a file called "df0.adf" in the RAM disk. These files are pretty
big, 524288 bytes for the ROM image and 901120 bytes for a disk image. If you
are short on RAM (less than 1.5MB) you may want to transfer those files
directly to a serial link between the Amiga and your Un*x system (works
without a problem for me).
transdisk can take extra arguments: A device name and unit number. If you do

  transdisk >ram:df1.adf trackdisk 1

the program will read the data from drive 1, not drive 0.

The current transdisk can only read the standard AmigaDOS format. You will
not be able to transfer copy protected disks. Although the current emulator
version can handle a second type of disk file, and I have successfully
transferred and run a copy protected game (Turrican I) on the emulator, this
support is preliminary, and the disk file format for non-standard disk formats
will probably change in future versions. If you also have Turrican and want
the program I used to transfer the disk, mail me.

If you transfer commercial software, you must not distribute the resulting
image files, since that would be a violation of copyright law. The Kickstart
ROM has to be considered commercial software. You may only use the Kickstart
from your own Amiga, and you may not distribute Kickstart ROM files.
Please read the license that came with your software for details.

If you have a disk image file, and you want to retrieve the files from it, you
can use the "readdisk" tool. It is automatically built by "make". If you have
a disk image of a disk called "Workbench1.3D" as df0.adf, and you do
   readdisk df0.adf
the whole directory structure of the disk image will be stored in a newly
created subdirectory called "Workbench1.3D". You can optionally give a second
parameter to specify a directory where to create the output other than the
current directory.

7. Quick overview of the debugger commands

If you use the X Windows version, you can press ^C at any time to enter the
built-in MC68000 debugger.
Each debugger command consists of a single letter and occasionally some
parameters.

g:                    Start execution at the current address.
c:                    Dump state of the CIA and custom chips.
r:                    Dump state of the CPU
m <address> <lines>:  Memory dump starting at <address>
d <address> <lines>:  Disassembly starting at <address>
t:                    Step one instruction
z:                    Step through one instruction - useful for JSR, DBRA etc.
f <address>:          Step forward until PC == <address>
q:                    Quit the emulator. You don't want to use this command.

While the emulator is running, you can interrupt it with a SIGINT signal (^C).
(Don't do that in SVGAlib mode - use F12)

8. Current state of UAE

The following parts are already mostly complete:
  - MC68000 CPU: Almost done, some rare instructions are not emulated yet.
    I'd like to make this a 68020 emulation, but I need more info than I have
    about the special registers (MMU etc.)
    Maybe it will one day run Linux/68k!
  - Blitter: If there's no bug, it ought to be complete.
  - Timers: I think these are fully working, too.
  - Copper: Not much to emulate here :-)
  - Floppy disk: Standard AmigaDOS disks seem to work O.K., some special
    formats can be made to work (not yet really supported).
  - Playfield (display) hardware: Normal cases are working, as well as
    dual playfields, EHB and HAM and interlace (interlace only with correct
    aspect)
  - Mouse, Keyboard, Joystick: Mouse and joystick should be autocalibrating.
    Only DE and US are supported as keyboard languages.
  - Sprites: Still one or two bugs, but usually working.
  - Sound: Some support (Linux only). Not too useful right now. See below.

Not done:
  - "System control hardware": That's what the HRM calls sprite/playfield
    collisions/priorities. Only the most common priority settings are
    implemented.
  - Timing: It does not really behave like a real A500, but I don't think
    complete accuracy is necessary.

9. Input devices

Currently, the keyboard mapping used in the emulator is valid only for a
german keyboard. On other keyboards, some keys will be missing - sorry. If you
fix this for your national keyboard, I'd appreciate if you could send me a
patch. There are some beginnings of US keyboard support in the source.
The left and right mouse buttons are emulated. If you have a three button
mouse, the middle button will be the joystick button.
Mouse movement is reported to the emulated Amiga. In SVGAlib, you'll have no
problem positioning the mouse. In X Windows, the emulator defaults to a
special mode in which the mouse movement is adjusted so that sprite 0 and X
mouse pointer are located at the same position. If this should cause problems,
you can turn it off with F12.
If you use Linux and have the joystick driver kernel module, you can configure
UAE to use it. The joystick should be autocalibrating. Turn it a few times on
startup to get the calibration done. If this causes any problems, let me know.

10. Sound

You probably noticed the LINUX_SOUND configuration option. If defined, this
will make the emulator use /dev/dsp to output sound with 16 bit, at a frequency
of 44100KHz. Your soundcard has to support this rate. If it does not, your
results will be unpredictable.
If graphics output is enabled while sound is output, the emulator will be much
too slow on all current systems. The sound will not be continuous. Therefore,
a hack to turn off screen updates is provided: Press ScrollLock to disable
graphics, press it again to enable them (note: for X, you'll have to press it
twice each time).
The LINUX_SOUND_SLOW_MACHINE option will steal cycles from the CPU emulator.
The relative CPU speed will be reduced somewhat if this option is set. This may
lead to incompatibilities. The system should not be heavily loaded (no blitter
or disk activity) while sound is being played, or even this will be too slow.
Only a subset of the Amiga sound hardware is emulated. Attached channels are
not implemented, neither is CPU-driven output.

Currently, this implementation is good enough to play *Tracker modules and
some game title melodies. It is fast enough (on a P90) to play modules using a
Workbench player program if no other (Amiga) processes are active.

11. Speed

A Pentium with about 500MHz would be nice... (*)
but even a Pentium-90 is not that bad, if you set the frame rate to a high
value, e.g. 9. Animations will not be smooth if not all frames are drawn, but
the speed of the emulation will be considerably higher.
The speed of the emulation is not fixed. Programs that make heavy use of
blitter, copper and disk DMA will run somewhat slower than programs that only
use the CPU. More bitplanes and sprites will also slow things down. The speed
also depends very much on configuration options.
UAE can calculate the average time it needs to finish one Amiga frame. Use the
'c' debugging command. If you use SVGAlib, the average frame rate will be
displayed when you exit UAE, provided the library doesn't mess up your
text-mode screen when you exit.
Here's a small table of various systems (running random programs, all values
may vary about +/-20 ). Configuration is in the format
"display/#colors/frame rate/aspect". A real A500 has a fixed frame rate of
20ms.

Note: For SVGAlib, there is no big difference whether you use the right aspect
or not, so these figures have been omitted.

Configuration             i486   P90    HP
SVGAlib/256/5/n                !  50 !
SVGAlib/256/1/n                ! 100 !
SVGAlib/65536/5/n          130 !  60 !
SVGAlib/65536/1/n          300 ! 120 !
X, 256/5/n                     !     !
X, 65536/5/n                   !  60 !
X, 256/1/n                     !     !
X, 65536/1/y                   ! 200 !

Systems:
i486: i486-DX2-66, VLB
P90: Pentium-90, PCI
HP: HP Apollo 9000/720

So, if you configure for maximum speed, a Pentium-90 will be 5 times slower
than a real A500 at full frame rate. If you reduce the frame rate, is about
2-3 times slower.

(*) Try buying a 500MHz clock and a fire extinguisher :-)

12. Future projects

A lot of things can still be added to make this program more useful, and I
can't do everything at the same time. So, any help is welcome to speed up
the development of this program. If you have written an Amiga program and it
does not work with the emulator, it would help tremendously if you could try
to figure out why it's incompatible.
If you fix any bugs or implement new features, please mail me any of these
enhancements (see below for address). If they are any good, I will include
them into a new version of the emulator. You'll be credited for any of your
changes that make it into the source. Any format that suits you is welcome,
but "diff -u" output is preferred.
Of course, no one is obliged to do any work on UAE. I'll eventually get around
to implement all the stuff I want to have. If you are just enjoying this
program, you are doing what it was written for.

Various approaches how to write an Amiga emulator have been discussed in
comp.emulators.misc, comp.emulators.cbm and comp.sys.amiga.emulations. This
implementation tries to emulate the behaviour of the Amiga hardware. This
hardware is supposed to be a PAL A500 with Old Chipset. Any Kickstart version
can be used, and any amount of chipmem (256K - 2MB) can be configured.
Extending this to ECS should be no problem (although I don't really see the
point - the emulator can already handle 2MB chip, which is the best thing
about ECS), a 68020 emulation should be possible as well, AGA may be tricky due
to lack of documentation.

13. Frequently Asked Questions

Q: Will there be a Windows version?
A: I'll never write a non-commercial program for DOS/Windows again. I hate
   having to reboot after mistakes.
   The odds are *very* low.

Q: I get lots of compilation errors. Why?
A: The most popular reason is a missing libg.sa in /usr/lib (Slackware bug).
   Do "cd /usr/lib; ln -s libc.sa libg.sa".
   Another possibility is that you botched your system in an ELF upgrade.
   Check whether GCC, binutils, libc, ld.so, X11 etc. are all uptodate and
   installed for the same binary format.

Q: How can I change diskfiles?
A: Wait for version 0.5.

Q: Is it possible to read Amiga disks with a PC?
A: Ask that in comp.emulators.misc :-) The answer is: NO! Unless you invent
   and build some extra hardware yourself, which no one appears to have done
   yet.

Q: When it starts up, it says "Illegal instruction: 4e7b". Why?
A: That's normal, it's just the Kickstart CPU type test.

Q: Why is there a blank area on the left side of the screen?
A: The Amiga can display graphics there, but usually doesn't because this
   would disable some sprites. The area is only used by some overscan demos.
   Normal screens are off-center.

Q: Benchmark program <foo> gives weird results.
A: Amiga programs run by the emulator think the Amiga timers can be used to
   measure real time. But in UAE, they only measure "emulation time". Sysinfo,
   for example, gives the same results on all machines. So don't run
   benchmarks to test the emulator speed.

Q: Wasn't this called the Unusable Amiga Emulator?
A: Yes. But no one thought the name was very fitting anymore, though. It was
   only really appropriate for v0.1, which couldn't even boot.

14. Thanks & Acknowledgements

Thanks to all who have written me so far with bugreports and success/failure
reports when trying to run the emulator on various hardware with different
Kickstart versions.

Special thanks (in no particular order) to:
  - Jay Miner, Dale Luck, R.J. Mical and all the others who built the Amiga.
  - Felix Bardos, whose HRM I "borrowed".
  - Alessandro Bissacco: X Windows mouse auto-calibration, battclock emulation
    and various bugfixes.
  - Hannu Rummukainen: Floppy write emulation.
  - Andre Beck: Made the X support much faster by using MIT-SHM extensions.
    (Not bad for a 10 minute hack, Andre!)
  - Ed Hanway: Wrote the unixfs.device. Improvements to the X support (cursor
    blanking, etc.), lots of SGI compatibility fixes, run time options. He
    also sent me a copy of his own (unfinished) Amiga emulator...
  - Ernesto Corvi: Mac port
  - Denis Sablic: Misc. bugfixes, "-S" runtime option.
  - Marcus Sundberg: Better transdisk, bugfixes, DEC Alpha diagnostics.

15. The author's address

[e-mail]

or, via snailmail

Bernd Schmidt
Schlossweiherstrasse 14
52072 Aachen
Germany

I'll *try* to reply to everyone who sends me mail. Email has a near 100%
chance of being replied, although I've been getting quite a lot of it
recently. I can't make any guarantees about snailmail.

I have set up a WEB page for UAE. You might find interim versions, Linux
binaries, diskfiles with Amiga software and other interesting stuff there.
Then again, you might not. My quota isn't that big. The address is

http://www-users.informatik.rwth-aachen.de/~crux/uae.html